ParcelLabel API

How to generate international parcel labels for parcels being sent from overseas locations

When generating parcel labels for packages originating from outside of New Zealand, merchants are able to choose the shipping method for how the parcel will be delivered to its destination. NZ Post currently offers the following services for customers:

• International Courier (tracked) - courier service into New Zealand. Refer to Create Label(s) International Inbound to NZ (Offshore)
• ETOE (Please speak to your NZ Post account manager)

These services need to be enabled by NZ Post before a merchant can use the service. Please contact your NZ Post account manager to activate the service you require.

Resource URL

UAT:

https://api.uat.nzpost.co.nz/parcellabel/v3/labels

Production:

https://api.nzpost.co.nz/parcellabel/v3/labels

A unique consignment_id is returned once the details of the request are stored in the labeling database. One or multiple labels can be generated within a consignment (for International Courier only)

Request Parameters

For each of these services, the parameter requirements are similar but each service has slightly different requirements and needs to use the relevant service code. In the following table, we have provided which fields are required in the label request for a particular service. Additional requirements for Courier Tracked services are listed beneath the standard parameters.

Code samples for each of these separate service types are displayed further down this page.

Field Name	Description	Required for ETOE?
carrier	Carrier of the parcel. Value must be PARCELPOST	Yes - ParcelPost
logo_id	Unique identifier for merchants logo. The field is only relevant for Courier services	N/A
format	Format of the label. Value must be PDF or PNG. Default Value is PDF.	No
notification_endpoint	Merchants Webhook URL to receive notification when the label has been generated.	No
delivery_choice_type	Additional service requested for the delivery. Value is a string and must be either 1 or 2.	No
sender_reference_1	Sender's reference for the consignment. Will be printed on the label.	No
sender_reference_2	Sender's reference. Will not be printed on the label.	No
label_dimensions	An object specifying the label dimensions (in mm) upon which to print the label. If you are passing this object then the value should be 150x100 or 174x100 or empty string. If it is empty then default value is 174x100. This field is only mandatory to generate 150x100 dimensions label.	NA
paper_dimensions	An object containing the paper size upon which to print the label. See Paper Dimension Object Parameters section.	No
paper_dimensions.width_cm	Width the label to be printed to. Default value is 17.4. Note: To print on a 150x100 label this value must be set to ‘15.0’	No
paper_dimensions.height_cm	Height of the label to be printed to. Default value is 10	No
paper_dimensions.stationery_size	Paper size upon which to print the label. Must be A4 or A5.	No
sender_details	An object containing the sender contact details. See Sender Details Object Parameters below.	Yes
sender_details.name	Name of the sender.	Yes
sender_details.phone	Phone number of the sender. NO SPACES, DIGITS and '+' ONLY	Yes
sender_details.email	Email address of the sender.	No but highly desirable
sender_details.fax	Contact fax number of the sender	No
sender_details.signatory	Name of the individual sending the parcel, this is used for customs purposes.	No
sender_details.company_name	Company name of the sender.	No
sender_details.site_code	Site code assigned to the address where the parcel will be picked up by the courier. This address is also used for the NZ Post manifest process.	No
sender_details.customs_code	Customs code of the sender.	No
receiver_details	An object containing the receiver contact details. See Receiver Details Object Parameters below.	Yes
receiver_details.name	Name of the receiver.	Yes
receiver_details.phone	Contact phone number of the receiver. NO SPACES, DIGITS and '+' ONLY	No but highly desirable
receiver_details.email	Email address of the receiver.	No but highly desirable
receiver_details.fax	Fax number of the person to receiver.	No
receiver_details.vat_number	The VAT or GST number of the receiver. The field should not be > 14 characters.	No
receiver_details.registration_number	Registration number of the receiver required for Delivery Location Options.	No
pickup_address	An object containing the sender pickup address details. See Pickup Address parameters below	Yes (NB: this can be used as the NZ return address for this service)
Courier pickup_address rules: country_code (mandatory) AND: only one of the following is required: address_id (highly desirable) OR dpid (highly desirable) OR site_code (highly desirable) OR street, suburb, city, and postcode. Use the city for addresses without suburbs.	Address_id and dpid can be obtained using ParcelAddress API. Account managers set up site codes.
pickup_address.company_name	Company name of the pickup address	No
pickup_address.building_name	Building name of the pickup address.	No
pickup_address.street_number	Street number of the pickup address.	No but highly desirable
pickup_address.street	Street name of the pickup address.	Yes
pickup_address.suburb	Suburb of the pickup address	No but highly desirable
pickup_address.city	City of the pickup address	Yes
pickup_address.state	Regional, provincial or county name of the pickup address.	No but highly desirable
pickup_address.locality_code	Country subdivision code identifier that the pickup address belongs to.	No
pickup_address.country_code	Two character country code of the pickup address. The value must be NZ	Yes
pickup_address.postcode	Postal or zip code of the pickup address.	Yes
delivery_address	An object containing the receiver delivery address details. See Receiver Address Object Parameters section	Yes
delivery_address rules: country_code (mandatory) AND: only one of the following is required: address_id (highly desirable) OR dpid (highly desirable) OR site_code OR street, suburb, city, and postcode. Use the city for addresses without suburbs.	Address_id and dpid can be obtained using ParcelAddress API. Account managers set up site codes.
delivery_address.location_type	Type of the delivery requested for the item. Value must be from UPU code list 199.	No
delivery_address.building_name	Building name of the delivery address.	No
delivery_address.company_name	Name of company that the parcel is being delivered to.	No
delivery_address.street_number	Street number of the delivery address.	No but highly desirable
delivery_address.street	Street name of the delivery address.	Yes
delivery_address.suburb	Suburb of the delivery address	No but highly desirable
delivery_address.city	City of the delivery address	Yes
delivery_address.state	State name of the delivery address	No
delivery_address.locality_code	Country subdivision code identifier that the delivery address belongs to.	No
delivery_address.country_code	Two character country code of the delivery address. For domestic labels, this must be set to NZ.	Yes
delivery_address.postcode	Postal or zip code of the delivery address.	Yes
delivery_address.instructions	Delivery instructions for courier	No
return_address	An object containing the sender return address details. See Return Address parameters below	No
Courier return_address rules: country_code (mandatory) AND: only one of the following is required: address_id (highly desirable) OR dpid (highly desirable) OR site_code (highly desirable) OR street, suburb, city, and postcode. Use the city for addresses without suburbs.	Address_id and dpid can be obtained using ParcelAddress API. Account managers set up site codes.
return_address.company_name	Company name of the return address	No
return_address.building_name	Building name of the return address.	No
return_address.street_number	Street number of the return address.	No but highly desirable
return_address.street	Street name of the return address.	Yes
return_address.suburb	Suburb of the return address	No but highly desirable
return_address.city	City of the return address	Yes
return_address.state	Regional, provincial or county name of the return address.	No but highly desirable
return_address.locality_code	Country subdivision code identifier that the return address belongs to.	No
return_address.country_code	Two character country code of the return address.	Yes
return_address.postcode	Postal or zip code of the return address.	Yes
parcel_details	An object containing the label details for each label in the consignment. See Parcel Details Object Parameters section	Yes
parcel_details.service_code	Code to represent a delivery service. This is the service code.	Yes
parcel_details.receiver_charging_arrangement	Duty and tax payment method as it applies to the item. Value must be DDP (Delivery Duty Paid) OR DDU (Delivery Duty Unpaid)	No
parcel_details.undeliverable_instructions	Instructions in case of non-delivery. Value must be NONE, RETURN or DESTROY.	Yes
parcel_details.indicia_number	Your indicia number	Yes
parcel_details.insurance_required	Whether insurance is required for the parcel. Value must be either TRUE or FALSE	Yes
parcel_details.nature_of_transaction_code	Category of goods that appears on the CN23 form. Value depends on the nature of the items. Must be one of: 11 = Sales of goods; 21 = Returned Goods; 31 = Gift; 32 = Commercial Sample; 91 = Documents; 999 = Other	Yes
parcel_details.postage_paid_amount	Monetary value of postage that sender has paid. Value must be greater than 0.	No
parcel_details.additional_fee_amount	Monetary value of other fees that sender has paid. E.g. additional insurance	No
parcel_details.insured_value_amount	Monetary value the parcels are insured for.	No
parcel_details.currency	Currency code for the parcel	Yes
parcel_details.dimensions	An object containing the dimension details of a parcel. See Parcel Details - Dimension Object Parameters section.	Yes
parcel_details.dimensions.length_cm	Length of the parcel.	Yes
parcel_details.dimensions.width_cm	Width of the parcel.	Yes
parcel_details.dimensions.height_cm	Height of the parcel.	Yes
parcel_details.dimensions.weight_kg	Physical weight of the parcel in kilograms.	No
parcel_details.dangerous_goods	An object containing the hazard identification information of a parcel. See Parcel Details - Dangerous Goods Object Parameters section.	No
parcel_details.dangerous_goods.hazard_class	Classification of dangerous items in the parcel. Value must be from Hazard Identification Code List at: http://www.ilo.org/legacy/english/protection/safework/cis/products/safetytm/tranann5.htm	No
parcel_details.dangerous_goods.type_code	United Nations Dangerous Goods identification code for dangerous items in the parcel. Value must be 4 digits.	No
parcel_details.parcel_contents	An array containing content details of a parcel.	Yes
parcel_details.parcel_contents.content_number	Number specifying an item in the parcel. Value must be an integer between 1 to 20 inclusive.	Yes
parcel_details.parcel_contents.description	Description of the parcel contents.	Yes
parcel_details.parcel_contents.harmonised_system_tariff	Internationally standardized name and number of the classification of the parcel content.	No
parcel_details.parcel_contents.quantity	Quantity of units in the parcel.	Yes
parcel_details.parcel_contents.weight_kg	Weight of each individual unit in the parcel(kgs).	Yes
parcel_details.parcel_contents.value	Dollar value of each individual unit in the parcel.	Yes
parcel_details.parcel_contents.country_code	Country code of the location in which the content piece was produced or manufactured. Value must be 2 characters.	No
parcel_details.accompanying_documents	An object containing the accompanying document information of a parcel. See Parcel Details - Accompanying Documents Object Parameters section	No
parcel_details.accompanying_documents.type	Code must be one of an allowed subset of codes. Value must be one of: LIC, 811 or 911.	No
parcel_details.accompanying_documents.identifier	Value entered on the CN23 license box.	No

Courier Base Services

The following are sample base service codes for International inbound parcel and satchel courier services

Courier Satchel Sizes

Where the parcel is a satchel (and you intend to send as a satchel), and the service code has not been selected via the ShippingOptions API, then the envelope size must be concatenated to the end of the service code before submitting the label request e.g. IWOLTPSFS

Below is a list of valid satchel sizes.

Courier Add ons

The following are sample value add-ons.

Courier Add-on Rules

The following rules apply to add-on services included in a label request:

1. Add-on services can only be present when the carrier is CourierPost
2. Only one of the following can be present on the label request: IWXOLRD Courier Rural Delivery, IWXOLSAT Courier Saturday Delivery, or IWXOLDG Courier Dangerous Goods
3. Signature required, IWXSR, may always be present

Merchants must ensure that when appropriate, the prepaid ticket corresponding to the requested add-on service is affixed to the parcel.

## Courier (174x100 label size example) – Australia to New Zealand (Pickup address is the return address in NZ)
{
    "carrier": "COURIERPOST",
    "orientation": "LANDSCAPE",
    "format": "PDF",
    "sender_reference_1": "Test 1",
    "sender_reference_2": "Test 2",
    "paper_dimensions": {
        "width_cm": 17.4,
        "height_cm": 10.0
    },
    "sender_details": {
        "name": "Koala ",
        "phone": "61438628100",
        "email": "info@koalapark.com.au",
        "company_name": "Koala Park Company",
        "site_code": 96306
    },
    "pickup_address": {
        "company_name": "Koala Park Company",
        "building_name": "Return to Sender Address",
        "unit_type": "Unit",
        "unit_value": "2",
        "floor": " 5",
        "street": "151 Victoria Street West",
        "suburb": "Auckland Central",
        "city": "Auckland",
        "country_code": "NZ",
        "postcode": "1010"
    },
    "receiver_details": {
        "name": "Tom Jones",
        "phone": "021-1234567",
        "email": "tomjones@example.co.nz"
    },
    "delivery_address": {
        "is_collection": false,
        "building_name": "Example building name Limited",
        "company_name": "Example Company Limited",
        "unit_type": "Suite",
        "unit_value": "4",
        "floor": "2",
        "street": "122 Kerwyn Avenue",
        "suburb": "East Tamaki",
        "city": "Auckland",
        "country_code": "NZ",
        "postcode": "2013",
        "instructions": "Ask for Tom Jones at reception"
    },
    "return_address": {
         "company_name": "Koala Park Company",
         "building_name": "Return to Sender Address",
         "unit_type": "Unit",
         "unit_value": "2",
         "floor": " 5",
         "street": "151 Victoria Street West",
         "suburb": "Auckland Central",
         "city": "Auckland",
         "country_code": "NZ",
         "postcode": "1010"
     },
    "parcel_details": [
        {
            "service_code": "IWOLP",
            "add_ons": [
                "IWSR"
            ],
            "return_indicator": "OUTBOUND",
            "currency": "NZD",
            "dimensions": {
                "length_cm": 15,
                "width_cm": 45,
                "height_cm": 35,
                "weight_kg": 2
            }
        },
        {
            "service_code": "IWOLP",
            "add_ons": [],
            "return_indicator": "RETURN",
            "dimensions": {
                "length_cm": 15,
                "width_cm": 45,
                "height_cm": 35,
                "weight_kg": 2
            }
        }
    ]
}

```

Courier (150x100 label size example) – Australia to New Zealand (Pickup address is the return address in NZ)

{
    "carrier": "COURIERPOST",
    "orientation": "LANDSCAPE",
    "format": "PDF",
    "sender_reference_1": "reference_1",
    "sender_reference_2": "reference_2",
    "label_dimensions": "150x100",
    "paper_dimensions": {
        "width_cm": 15.0,
        "height_cm": 10.0
    },
    "sender_details": {
        "name": "Koala",
        "phone": "61438628100",
        "email": "info@koalapark.com.au",
        "company_name": "Koala Park Company",
        "site_code": 96306
    },
    "pickup_address": {
        "company_name": "Koala Park Company",
        "building_name": "Pickup Address Building",
        "unit_type": "Unit",
        "unit_value": "2",
        "floor": "Floor 5",
        "street": "151 Victoria Street West",
        "suburb": "Auckland Central",
        "city": "Auckland",
        "country_code": "NZ",
        "postcode": "1010"
    },
    "receiver_details": {
        "name": "Tom Jones",
        "phone": "021-1234567",
        "email": "tomjones@example.co.nz"
    },
    "delivery_address": {
        "is_collection": false,
        "building_name": "Delivery Building Name",
        "company_name": "Example Company Limited",
        "unit_type": "Suite",
        "unit_value": "4",
        "floor": "Floor 2",
        "street": "122 Kerwyn Avenue",
        "suburb": "East Tamaki",
        "city": "Auckland",
        "country_code": "NZ",
        "postcode": "2013",
        "instructions": "Ask for Tom Jones at reception "
    },
    "return_address": {
          "company_name": "Koala Park Company",
          "building_name": "Return to Sender Address",
          "unit_type": "Unit",
          "unit_value": "2",
          "floor": " 5",
          "street": "151 Victoria Street West",
          "suburb": "Auckland Central",
          "city": "Auckland",
          "country_code": "NZ",
          "postcode": "1010"
    },
    "parcel_details": [
        {
            "service_code": "IWOLP",
            "add_ons": [
                "IWSR"
            ],
            "return_indicator": "OUTBOUND",
            "currency": "NZD",
            "dimensions": {
                "length_cm": 15,
                "width_cm": 45,
                "height_cm": 35,
                "weight_kg": 2
            }
        },
        {
            "service_code": "IWOLP",
            "add_ons": [],
            "return_indicator": "RETURN",
            "dimensions": {
                "length_cm": 15,
                "width_cm": 45,
                "height_cm": 35,
                "weight_kg": 2
            }
        }
    ]
}

ETOE - USA to Australia

{
    "carrier": "PARCELPOST",
    "orientation": "LANDSCAPE",
    "format": "PDF",
    "sender_reference_1": "22105921",
    "sender_reference_2": "NZP-TEST-012",
    "paper_dimensions": {
        "width_cm": 21.0,
        "height_cm": 29.7,
        "stationery_size": "A4"
    },
    "sender_details": {
        "name": "Bob Jones",
        "phone": "+64123456789",
        "email": "testdeliver@nzpost.co.nz"
    },
    "pickup_address": {
        "city": "Auckland",
        "suburb": "Laurence Stevens Drive",
        "country_code": "NZ",
        "postcode": "2154",
        "street": "PO Box 210014"
    },
    "receiver_details": {
        "name": "John Smith",
        "phone": "+64 1234 56789",
        "email": "testing1234@nzpost.co.nz",
        "vat_number": "NONE"
    },
    "delivery_address": {
        "building_name": "Sydney Opera House",
        "street": "Bennelong Point",
        "city": "Sydney",
        "state": "New south wales",
        "postcode": "2000",
        "country_code": "AU"
    },
    "parcel_details": [
        {
            "service_code": "IEECONUS",
            "undeliverable_instructions": "RETURN",
            "insurance_required": false,
            "indicia_number": "247837",
            "nature_of_transaction_code": "32",
            "postage_paid_amount": 0.4,
            "currency": "USD",
            "dimensions": {
                "length_cm": 5.0,
                "width_cm": 15.0,
                "height_cm": 12.0,
                "weight_kg": 1.2
            },
            "parcel_contents": [
                {
                    "content_number": 1,
                    "country_code": "CN",
                    "description": "Waterproof Dog Coat",
                    "quantity": 1,
                    "value": 9.990,
                    "weight_kg": 0.400,
                    "harmonised_system_tariff": "1234.98.9876"
                },
                {
                    "content_number": 2,
                    "country_code": "VN",
                    "description": "Women's Long Sleeve Top",
                    "quantity": 1,
                    "value": 4.990,
                    "weight_kg": 0.500,
                    "harmonised_system_tariff": "XX 888"
                }
            ]
        }
    ]
}

Response Parameters

Sample Response

{
  "consignment_id": "DVZQYF",
  "message_id": "520f4fa0-22cc-11eb-b1e1-027414412442",
  "success": true
}